.TH std::counted_iterator 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary"
.SH NAME
std::counted_iterator \- std::counted_iterator

.SH Synopsis
   Defined in header <iterator>
   template< std::input_or_output_iterator I >  \fI(since C++20)\fP
   class counted_iterator;

   std::counted_iterator is an iterator adaptor which behaves exactly like the
   underlying iterator, except that it keeps track of the distance to the end of its
   range. This iterator is equal to std::default_sentinel if and only if its count
   reaches zero.

.SH Member types

   Member type       Definition
   iterator_type     I
   value_type        std::iter_value_t<I> if I models indirectly_readable; otherwise,
                     not defined
   difference_type   std::iter_difference_t<I>
   iterator_concept  I::iterator_concept if present; otherwise, not defined
   iterator_category I::iterator_category if present; otherwise, not defined

.SH Member objects

   Member name       Definition
   current (private) the underlying iterator which base() accesses
                     (exposition-only member object*)
                     the distance between the underlying iterator and the end of its
   length (private)  range
                     (exposition-only member object*)

.SH Member functions

   constructor     constructs a new iterator adaptor
   (C++20)         \fI(public member function)\fP
   operator=       assigns another iterator adaptor
   (C++20)         \fI(public member function)\fP
   base            accesses the underlying iterator
   (C++20)         \fI(public member function)\fP
   count           returns the distance to the end
   (C++20)         \fI(public member function)\fP
   operator*       accesses the pointed-to element
   operator->      \fI(public member function)\fP
   (C++20)
   operator[]      accesses an element by index
   (C++20)         \fI(public member function)\fP
   operator++
   operator++(int)
   operator+=
   operator+       advances or decrements the iterator
   operator--      \fI(public member function)\fP
   operator--(int)
   operator-=
   operator-
   (C++20)

.SH Non-member functions

   operator==                         compares the distances to the end
   operator<=>                        \fI(function template)\fP
   (C++20)
   operator==(std::default_sentinel)  checks if the distance to the end is equal to 0
   (C++20)                            \fI(function template)\fP
   operator+                          advances the iterator
   (C++20)                            \fI(function template)\fP
   operator-                          computes the distance between two iterator
   (C++20)                            adaptors
                                      \fI(function template)\fP
   operator-(std::default_sentinel_t) computes the signed distance to the end
   (C++20)                            \fI(function template)\fP
   iter_move                          casts the result of dereferencing the underlying
   (C++20)                            iterator to its associated rvalue reference type
                                      \fI(function)\fP
   iter_swap                          swaps the objects pointed to by two underlying
   (C++20)                            iterators
                                      \fI(function template)\fP

.SH Helper classes

                                               provides uniform interface to the
   std::iterator_traits<std::counted_iterator> properties of the std::counted_iterator
   (C++20)                                     type
                                               \fI(class template specialization)\fP

.SH Example


// Run this code

 #include <algorithm>
 #include <iostream>
 #include <iterator>
 #include <string>
 #include <vector>

 using std::operator""s;

 void print(auto const remark, auto const& v)
 {
     const auto size = std::ssize(v);
     std::cout << remark << '[' << size << "] { ";
     for (auto it = std::counted_iterator{std::cbegin(v), size};
          it != std::default_sentinel; ++it)
         std::cout << *it << (it.count() > 1 ? ", " : " ");
     std::cout << "}\\n";
 }

 int main()
 {
     const auto src = {"Arcturus"s, "Betelgeuse"s, "Canopus"s, "Deneb"s, "Elnath"s};
     print("src", src);
     std::vector<decltype(src)::value_type> dst;
     std::ranges::copy(std::counted_iterator{src.begin(), 3},
                       std::default_sentinel,
                       std::back_inserter(dst));
     print("dst", dst);
 }

.SH Output:

 src[5] { Arcturus, Betelgeuse, Canopus, Deneb, Elnath }
 dst[3] { Arcturus, Betelgeuse, Canopus }

   Defect reports

   The following behavior-changing defect reports were applied retroactively to
   previously published C++ standards.

     DR    Applied to      Behavior as published               Correct behavior
                      member typedefs are not provided member typedefs are added to
                      std::incrementable_traits        account for iterator_traits fix
   P2259R1 C++20      is specialized for               redundant
                      counted_iterator                 std::incrementable_traits
                                                       specialization is removed

.SH See also

   default_sentinel_t default sentinel for use with iterators that know the bound of
   (C++20)            their range
                      \fI(class)\fP
   views::counted     creates a subrange from an iterator and a count
   (C++20)            (customization point object)
   ranges::take_view  a view consisting of the first N elements of another view
   views::take        \fI(class template)\fP (range adaptor object)
   (C++20)
